# Translation API Reference

The Translation API allows you to translate text content between different locales while maintaining formatting. It supports various text formats and includes caching capabilities for improved performance.

## Authentication

All API requests require authentication using an API key. Include your API key in the request headers:

```bash
x-api-key: your-api-key
```

## Endpoints

### Translate Text

`POST /api/translate`

Translates text content between specified locales.

#### Request Body

```json
{
  "projectId": "string",
  "sourceLocale": "string",
  "targetLocale": "string",
  "format": "string",
  "sourceText": "string",
  "cache": boolean
}
```

#### Response

**Success Response (200 OK)**

```json
{
  "success": true,
  "translatedText": "string",
  "cached": boolean
}
```

**Error Response (4xx, 5xx)**

```json
{
  "success": false,
  "error": "string"
}
```

#### Example Request

```bash
curl -X POST https://api.languine.com/api/translate \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "projectId": "proj_123",
    "sourceLocale": "en",
    "targetLocale": "es",
    "format": "md",
    "sourceText": "Hello world",
    "cache": true
  }'
```

#### Example Response

```json
{
  "success": true,
  "translatedText": "Hola mundo",
  "cached": false
}
```

## Error Codes

The API uses conventional HTTP response codes to indicate the success or failure of requests:

- `401` - Invalid or missing API key
- `400` - Invalid request parameters
- `403` - API key valid but insufficient permissions or exceeded limits
- `500` - Server error

## Rate Limiting

API requests are subject to rate limiting based on your project's configuration. The limits are verified for each API key and project combination.

## Caching

The API supports optional caching of translation results. When `cache` is set to `true`:
1. Before translation, the system checks for a cached version
2. If found, returns the cached translation
3. If not found, performs the translation and caches the result for future use

## Supported Formats

The API supports various text formats including:
- `string` - Plain text strings
- `json` - JSON files and objects
- `yaml` - YAML files
- `properties` - Java properties files
- `android` - Android string resources
- `xcode-strings` - iOS/macOS .strings files
- `xcode-stringsdict` - iOS/macOS .stringsdict files
- `xcode-xcstrings` - iOS/macOS .xcstrings files
- `md` - Markdown
- `mdx` - MDX (Markdown with JSX)
- `html` - HTML files
- `js` - JavaScript files
- `ts` - TypeScript files
- `po` - Gettext PO files
- `xliff` - XLIFF translation files
- `csv` - CSV files
- `xml` - XML files
- `arb` - Application Resource Bundle files
- `ftl` - Fluent FTL files
- `php` - PHP files

Additional formats may be supported based on your project configuration.
